<?php

interface GDGE_Location_Interface
{
	/**
	 * 
	 * Return location identifier
	 * @return mixed Location identifier
	 */
	public function getIdentifier();
	
	/**
	 * Get an array of sublocations, that are part of this location
	 * @return array sublocations
	 */
	public function getSubLocations();
	
	/**
	 * Get the location above this level, null if this is a top-level location
	 * @return GDGE_Location_Interface|null
	 */
	public function getSuperLocation();
	
	/**
	 * 
	 * Returns true if the locations are the same
	 * @param GDGE_Location_Interface $location
	 * @return boolean
	 */
	public function equals(GDGE_Location_Interface $location);

	/**
	 * 
	 * Returns true if this location equals or is part of a larger location
	 * (is a sublocation of the parameter
	 * 
	 * @param GDGE_Location_Interface $location
	 * @return boolean
	 */
	public function isPartOf(GDGE_Location_Interface $location);
	
	/**
	 * Returns true if $location equals or is a sublocation of this location
	 * @param GDGE_Location_Interface $location
	 * @return boolean
	 */
	public function contains(GDGE_Location_Interface $location);

}